Motor Invoice OCR API

API Description

Objective

The Motor Invoice OCR API extracts the textual data from an image of a motor invoice document and returns it in a JSON format.

Input	Output
An image or PDF file containing a motor invoice document.	The textual information extracted from the document.

API URL

https://ind-engine.thomas.hyperverge.co/v1/readMotorInvoice

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and ﬁles as form-data through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Type	Description	Valid Values
content-type	Mandatory	string	This parameter defines the media type for the request payload.	multipart/form-data
`appId`	Mandatory	string	The application ID shared by HyperVerge	Not Applicable - this is a unique value.
`appKey`	Mandatory	string	The application key shared by HyperVerge	Not Applicable - this is a unique value.
`transactionId`	Mandatory	string	The unique ID for the customer journey.	Not Applicable - this is a unique value related to a transaction in your application.

Inputs

The following table provides the complete information on the parameters used in the request body for the API call.

Parameter	Mandatory or Optional	Description
`image`	Mandatory	The image file containing the motor invoice document.

Caution

If you send multiple files in the same API request, the OCR extraction will be performed only on one of the files. Kindly send only one file in a request to avoid confusion.
If the PDF file has multiple pages, only the first page will be considered for the OCR extraction.

Sample Request

The following code shows a standard curl request for the API.

curl --location --request POST 'https://ind.thomas.hyperverge.co/v1/readMotorInvoice' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'image=@"<path_to_image_file>"'

Success Response

The following is a successful response sample:

{
  "status": "success",
  "statusCode": "200",
  "result": [
    {
    "details": {
        "totalAmountInWords": {
          "value": "<Total_Amount_In_Words>"
        },
        "totalAmountInFigures": {
          "value": "<Total_Amount_In_Figures>"
        },
        "customerName": {
          "value": "<Customer_Name>"
        },
        "chasisNumber": {
          "value": "<Chassis_Number>"
        },
        "engineNumber": {
          "value": "<Engine_Number>"
        },
        "dealerName": {
          "value": "<Dealer_Name>"
        },
      "invoiceNumber": {
          "value": "<Invoice_Number>"
      },
      "invoiceDate": {
          "value": "<Invoice_Date_in_DD/MM/YYYY_Format>"
      },
        "GSTINNumber": {
          "value": "<GSTIN_Number>"
      },
        "CGSTAmount": {
          "value": "<CGST_Amount>"
      },
        "SGSTAmount": {
          "value": "<SGST_Amount>"
        }
      }
    }
  ],
  "metaData": {
     "requestId": "<Request_ID>",
          "transactionId": "<Transaction_ID>"
  }
}

Success Response Details

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The HTTP status code returned for the request
result	array	Array containing the extracted details from the motor invoice
result[].details	object	Object containing the extracted fields with their values
result[].details.totalAmountInWords	object	Total amount in words extracted from the motor invoice
result[].details.totalAmountInWords.value	string	The actual total amount in words
result[].details.totalAmountInFigures	object	Total amount in figures extracted from the motor invoice
result[].details.totalAmountInFigures.value	string	The actual total amount in figures
result[].details.customerName	object	Customer name extracted from the motor invoice
result[].details.customerName.value	string	The actual customer name value
result[].details.chasisNumber	object	Chassis number extracted from the motor invoice
result[].details.chasisNumber.value	string	The actual chassis number value
result[].details.engineNumber	object	Engine number extracted from the motor invoice
result[].details.engineNumber.value	string	The actual engine number value
result[].details.dealerName	object	Dealer name extracted from the motor invoice
result[].details.dealerName.value	string	The actual dealer name value
result[].details.invoiceNumber	object	Invoice number extracted from the motor invoice
result[].details.invoiceNumber.value	string	The actual invoice number value
result[].details.invoiceDate	object	Invoice date extracted from the motor invoice
result[].details.invoiceDate.value	string	The actual invoice date value
result[].details.GSTINNumber	object	GSTIN number extracted from the motor invoice
result[].details.GSTINNumber.value	string	The actual GSTIN number value
result[].details.CGSTAmount	object	CGST amount extracted from the motor invoice
result[].details.CGSTAmount.value	string	The actual CGST amount value
result[].details.SGSTAmount	object	SGST amount extracted from the motor invoice
result[].details.SGSTAmount.value	string	The actual SGST amount value
metaData	object	Metadata object containing request tracking information
metaData.requestId	string	Unique identifier for the API request
metaData.transactionId	string	Unique identifier for tracking the user journey

Error Responses

Missing Input Image
Image Size Issue
Incorrect Document Type

{
  "status": "failure",
  "statusCode": 400,
  "error": "API call requires one input image",
  "metaData": {
        "requestId": "<Request_ID>",
          "transactionId": "<Transaction_ID>"
    }
}

{
  "status": "failure",
  "statusCode": 400,
  "error": "image size cannot be greater than 6 MB",
  "metaData": {
        "requestId": "<Request_ID>",
          "transactionId": "<Transaction_ID>"
    }
}

{
  "status": "failure",
  "statusCode": 422,
  "error": "Document Not Detected",
  "metaData": {
       "requestId": "<Request_ID>",
          "transactionId": "<Transaction_ID>"
    }
}

Error Response Details

A failure or error response from the module contains a failure status, with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description
400	No Image input	The request missed the `image` input.
400	image size cannot be greater than 6MB	The image size is larger than the allowed limit.
422	Document Not Detected	The image file in the request is not a valid motor invoice document.
5xx	Internal Server Error	There was an error with HyperVerge's server. Please contact the HyperVerge team.

API Description​

Objective​

API URL​

Overview​

Authentication​

API Request Details

Method - POST

Headers

Inputs​

Sample Request​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​